精確描述函數行為

// 傳回這個檔案的行數
int CountLines(string filename){...}

這段註解十分不精確-「一行」有許多不同的定義方式，如：

• ""(空檔案) - 0或1行？
• "hello" - 0或1行？
• "hello\n" - 1或2行？
• "hello\n world" - 1或2行？
  最簡單的方式是計算換行字元(\n)：

// 計算檔案中換行位元個數('\n')
int CountLines(string filename){...}

使用具代表性的輸入/輸出範例

以下是常見的移除部份字串函數：

// 從輸入字串 'src' 中移除 'chars' 字首/字尾
String Strip(Strin tsrc,String chars){...}

註解不夠精確，無法回答以下疑問：

• chars 是會被移除的子字串，或只是個沒有個特定順序的字元集合？
• 如果src的結尾有多組 chars 重複出現會如何？
  只需要一個例子就能夠回答這些問題：

// ...
// 範例：Strip("abaa/a/ba", "ab") 傳回"/a/"
String Strip(Strin tsrc,String chars){...}

要注意太過簡單無法回答所有的問題的例子，就沒有太大的幫助：

// 範例：Strip("ab", "a") 傳回"b"

Reference

• <<易讀程式之美學－提升程式碼可讀性的簡單法則 >>(The Art of Readable Code)